refactor(runtime): unify local entrypoint ownership - #1833

Summary

• establish one runtime-ownership policy for first-party local entrypoints without making CLI depend on or start SDK Host
• keep Embedded as the default; only interactive TUI can explicitly opt into Shared mode with --shared
• unify session-creation facts around AgentSessionCreateResult, while preserving the SDK Host protocol adapter and Desktop wire compatibility
• make Snapshot workspace scope explicit, canonicalized, and fail-closed for remote sessions without duplicating runtime owners

Entrypoint model

Read-only session listing and viewing do not acquire ownership. Session mutation, restore, or attach paths do. Shared ownership is exclusive per canonical workspace and product; compatible Embedded processes can coexist.

Compatibility and safety

• remote workspace identity must be verified by the workspace owner; remote requests never fall back to a matching local path
• disconnected remote Snapshot requests retain their structured connection binding and fail closed
• historical local sessions with persisted workspaceHostname=localhost remain local because host data is carried only with an explicit remote connection identity
• canonical Snapshot manager initialization converges workspace aliases and preserves strict atomic writes on Windows long paths
• Snapshot path checks compare both raw and canonical paths, resolve missing descendants through their nearest existing ancestor, keep .git and runtime roots protected, and use case-insensitive scope checks on Windows
• built-in Write reuses its tool-owned permission-intent parser for Snapshot tracking, while Delete/Edit keep the exact input path they mutate; Snapshot-tracked local Delete fails closed for symlink or reparse-point objects that the current byte snapshot format cannot faithfully restore
• Desktop keeps its existing response shape as an alias of the common session-creation result; SDK Host retains protocol-only fields in its adapter DTO

During rebase, upstream added deferred session/worktree isolation. The merged restore order is intentionally:

1. resolve the persistence/storage workspace;
2. resolve the typed local or remote restore scope;
3. acquire runtime ownership before restoring an unloaded session;
4. verify ownership again for the loaded or restored session before mutation/attach.

Documentation

The runtime deployment, Agent SDK product, and product architecture documents now include entrypoint and ownership diagrams. PR-specific design and execution notes remain local under .tmp and are not included.

Size

Validation

• cargo check --locked --workspace
• cargo test --locked -p bitfun-core -p bitfun-desktop
• Core: 1,578 passed, 1 ignored
• Desktop: 189 passed
• exact CI path-alias reproduction with TEMP and TMP pointing through a Windows junction
• CLI: 368 passed plus all integration targets
• SDK Host library/app, process-initialization, stdio, and lifecycle tests
• Server: 12 passed
• runtime ownership, JSON store, runtime ports, and Agent Runtime focused tests
• Web Snapshot API: 5 passed
• Web full suite: 342 files / 2,237 tests passed, excluding only the pre-existing Windows CRLF-sensitive RemoteConnectDialog.contract.test.ts
• pnpm run type-check:web
• pnpm run lint:web
• core boundary checks and tests
• repository hygiene and i18n audit
• git diff --check gcwing/main...HEAD

The branch was rebased onto gcwing/main@93c39eae6; upstream's readable managed-worktree naming and Task subagent cancellation changes remain intact. Independent architecture and product reviews were run against the complete diff. Their path-safety, Write payload, Delete symlink, Windows case-folding, and historical localhost-session findings were fixed and covered before final approval (P0/P1/P2 = 0 in both reviews).